package annuaire.dao;

import java.util.Collection;

import annuaire.beans.Admin;
import annuaire.beans.Promotion;
import annuaire.beans.Student;
import annuaire.exceptions.DaoException;

/**
 * Interface de la DAO (Data Access Objet) servant à gérer les objets
 * persistants.
 * 
 * @author Yannick Lorenzati & Stephanie Malakian
 * 
 */
public interface IAnnuaireDao {

	/**
	 * Initialisation de la DAO.
	 */
	public void init();

	/**
	 * Fermeture de la DAO.
	 */
	public void close();

	/**
	 * Ajoute un administrateur en base.
	 * 
	 * @param a
	 *            Administrateur à ajouter.
	 * @return L'administrateur ajouté.
	 * @throws DaoException
	 */
	public Admin addAdmin(Admin a) throws DaoException;

	/**
	 * Ajoute une promotion en base.
	 * 
	 * @param p
	 *            Promotion à ajouter.
	 * @return La promotion ajoutée.
	 * @throws DaoException
	 */
	public Promotion addPromo(Promotion p) throws DaoException;

	/**
	 * Ajoute un étudiant en base.
	 * 
	 * @param s
	 *            Etudiant à ajouter.
	 * @return L'étudiant ajouté.
	 * @throws DaoException
	 */
	public Student addStudent(Student s) throws DaoException;

	/**
	 * Supprime un administrateur de la base.
	 * 
	 * @param a
	 *            Administrateur à supprimer.
	 * @throws DaoException
	 */
	public void removeAdmin(Admin a) throws DaoException;

	/**
	 * Supprime une promotion de la base.
	 * 
	 * @param p
	 *            Promotion à supprimer.
	 * @throws DaoException
	 */
	public void removePromo(Promotion p) throws DaoException;

	/**
	 * Supprime un étudiant de la base.
	 * 
	 * @param s
	 *            Etudiant à supprimer.
	 * @throws DaoException
	 */
	public void removeStudent(Student s) throws DaoException;

	/**
	 * Met à jour un administrateur dans la base.
	 * 
	 * @param a
	 *            Administrateur à mettre à jour.
	 * @return L'administrateur mis à jour.
	 * @throws DaoException
	 */
	public Admin updateAdmin(Admin a) throws DaoException;

	/**
	 * Met à jour une promotion dans la base.
	 * 
	 * @param p
	 *            Promotion à mettre à jour.
	 * @return La promotion mise à jour.
	 * @throws DaoException
	 */
	public Promotion updatePromo(Promotion p) throws DaoException;

	/**
	 * Met a jour un étudiant dans la base.
	 * 
	 * @param s
	 *            Etudiant à mettre à jour.
	 * @return L'étudiant mis à jour.
	 * @throws DaoException
	 */
	public Student updateStudent(Student s) throws DaoException;

	/**
	 * Liste toutes les promotions.
	 * 
	 * @return La liste des identifiants des promotions, null si aucune
	 *         promotion n'a été trouvée.
	 * @throws DaoException
	 */
	public Collection<Integer> listPromotions() throws DaoException;

	/**
	 * Liste les tous les etudiants
	 * 
	 * @param idPromo
	 *            Identifiant de la promotion.
	 * @return La liste des identifiants des étudiants faisant partie de cette
	 *         promotion, null si aucun etudiant n'a été trouvé.
	 * @throws DaoException
	 */
	public Collection<Integer> listStudents() throws DaoException;

	/**
	 * Liste les etudiants appartenant à une promotion.
	 * 
	 * @param idPromo
	 *            Identifiant de la promotion.
	 * @return La liste des identifiants des étudiants faisant partie de cette
	 *         promotion, null si aucun etudiant n'a été trouvé.
	 * @throws DaoException
	 */
	public Collection<Integer> listStudents(int idPromo) throws DaoException;

	/**
	 * Recherche des nbResult premiers administrateurs dans la base qui
	 * correspondent à un modèle de recherche.
	 * 
	 * @param pattern
	 *            Administateur servant de modèle de recherche.
	 * @param nbResult
	 *            Nombre entier indiquant le nombre maximum de résultats
	 *            retournés.
	 * @return La collection d'Administrateurs correspondant à la recherche, ou
	 *         NULL si la recherche ne correspond à aucun administrateur.
	 * @throws DaoException
	 *             Si aucun critère n'est précisé (i.e. si l'administrateur
	 *             servant de modèle vaut null), ou si le nombre est invalide.
	 */
	public Collection<Admin> searchAdmin(Admin pattern, Integer nbResult)
			throws DaoException;

	/**
	 * Recherche d'un administrateur dans la base qui corresponde à un id.
	 * 
	 * @param idAdmin
	 *            Id de l'administateur servant de modèle de recherche.
	 * @return L'Administrateur correspondant à la recherche, ou NULL si la
	 *         recherche ne correspond à aucun administrateur.
	 * @throws DaoException
	 *             Si l'id précisé est invalide (i.e. negatif).
	 */
	public Admin searchAdminById(int idAdmin) throws DaoException;

	/**
	 * Recherche des nbResult premières promotions dans la base qui
	 * correspondent à un modèle de recherche.
	 * 
	 * @param pattern
	 *            Promotion servant de modèle de recherche.
	 * @param withStudents
	 *            Booléen indiquant si le résultat doit renvoyer la promotion
	 *            uniquement (withStudents vaut false) ou bien la promotion
	 *            ainsi que les étudiants qui en font partie (withStudents vaut
	 *            true).
	 * @param nbResult
	 *            Nombre entier indiquant le nombre maximum de résultats
	 *            retournés.
	 * @return La collection de promotions correspondant à la recherche, ou NULL
	 *         si la recherche ne correspond à aucune promotion.
	 * @throws DaoException
	 *             Si aucun critère n'est précisé (i.e. si la promotion servant
	 *             de modèle vaut null), ou si le nombre est invalide.
	 */
	public Collection<Promotion> searchPromo(Promotion pattern,
			boolean withStudents, Integer nbResult) throws DaoException;

	/**
	 * Recherche d'une promotion dans la base qui corresponde à un id.
	 * 
	 * @param idPromo
	 *            Id de la promotion servant de modèle de recherche.
	 * @return La promotion correspondant à la recherche, ou NULL si la
	 *         recherche ne correspond à aucune promotion.
	 * @throws DaoException
	 *             Si l'id précisé est invalide (i.e. negatif).
	 */
	public Promotion searchPromoById(int idPromo, boolean withStudents)
			throws DaoException;

	/**
	 * Recherche des nbResult premiers étudiants dans la base qui correspondent
	 * à un modèle de recherche.
	 * 
	 * @param pattern
	 *            Etudiant servant de modèle de recherche.
	 * @param nbResult
	 *            Nombre entier indiquant le nombre maximum de résultats
	 *            retournés.
	 * @return La collection d'étudiants correspondant à la recherche, ou NULL
	 *         si la recherche ne correspond à aucun étudiant.
	 * @throws DaoException
	 *             Si aucun critère n'est précisé (i.e. si l'étudiant servant de
	 *             modèle vaut null), ou si le nombre est invalide.
	 */
	public Collection<Student> searchStudents(Student pattern, Integer nbResult)
			throws DaoException;

	/**
	 * Recherche d'un étudiant dans la base qui corresponde à un id.
	 * 
	 * @param idStudent
	 *            Id de l'étudiant servant de modèle de recherche.
	 * @return L'étudiant correspondant à la recherche, ou NULL si la recherche
	 *         ne correspond à aucun étudiant.
	 * @throws DaoException
	 *             Si l'id précisé est invalide (i.e. negatif).
	 */
	public Student searchStudentById(int idStudent) throws DaoException;

	/**
	 * Ajout d'une collection d'étudiants à une promotion.
	 * 
	 * @param p
	 *            La promotion à laquelle on va rajouter des étudiants.
	 * @param students
	 *            La collection des étudiants à rajouter à la promotion.
	 * @return La promotion à laquelle on a rajouté les étudiants.
	 * @throws DaoException
	 */
	public Promotion addStudentsToPromo(Promotion p,
			Collection<Student> students) throws DaoException;

}
